Skip to main content
Version: 2.3

MQTT Interface

This document describes the MQTT topics that are used to communicate with viaSens devices.

note

Before using MQTT to communicate with a certain viaSens device, it needs to be provisioned and its gateway needs to be connected to MQTT broker. Specification relies on the MQTT version 3.1 or higher.

Smart Sensor MQTT Topics​

Topic Description Retain
/sauter/viasens/<network-id>/<node-address>

Node with the address of <node-address> that is part of <network-id> network posts sensor values to this topic in a Smart Sensor Data format.

Example below shows the packet describing humidity data posted to this topic.

{
  "type": "humid",
  "payload": {
    "humidity": 49
  }
}

By receiving the configuration packet, the device is sure the status packet was published over MQTT - meaning everything is ready for sending startup values of all sensors. Those values will also be sent every time the new configuration packet is received.

To this topic: Gateway publishes, MQTT broker subscribes.

no

/sauter/viasens/<network-id>/<node-address>/control

Control the node from the <network-id> network by posting message in a Smart Sensor Data format to this topic.

Example below shows the packet describing the control of the LED Ring.

{
  "type": "led-ring",
  "payload": {
    "mode": 1,
    "duration": 10000,
    "speed": 100,
    "colors": ["0x0000FF", "0x00FF00", "0xFF0000"]
  }
}

To this topic: Gateway subscribes, MQTT broker publishes.

no

/sauter/viasens/<network-id>/<node-address>/configure

Configure the node from the <network-id> network by posting RETAIN message in a Smart Sensor Config Data format to this topic.

Retaining a message ensures that the gateway can hard reset and still be able to collect the configuration of all nodes from the network.

Example below shows the packet describing the configuration of a single node.

{
  "type": "sensors-config",
  "payload": {
    "temperature": {
      "emissivity": 90,
      "source": 0,
      "ntc-offset": 0.0,
      "cov": 0.2,
      "report-time": 900,
      "dead-time": 300
    },
    "occupancy": {
      "hold-time": 3,
      "sensitivity": 1,
      "mode": 0,
      "report-time": 900
    },
    "humid": {
      "cov": 5,
      "report-time": 900,
      "dead-time": 300
    },
    "voc": {
      "cov": 100,
      "report-time": 900,
      "dead-time": 300
    },
    "co2": {
      "cov": 100,
      "report-time": 900,
      "dead-time": 300
    },
    "illuminance": {
      "slope": 1,
      "intercept": 0,
      "cov": 50,
      "report-time": 900,
      "dead-time": 300
    },
    "microphone": {
      "ceiling-type": 0,
      "cov": 5,
      "report-time": 900,
      "dead-time": 30
    },
    "ibeacon": {
      "enable": true,
      "tx-power": 4
    }
  }
}

To this topic: Gateway subscribes, MQTT broker publishes.

yes

/sauter/viasens/<network-id>/<node-address>/configure/feedback

Gateway sends the acknowledgment ("ack"/"fail") to this topic if the message published to the /sauter/viasens/<network-id>/<node-address>/configure gets acknowledged by the node device. If no acknowledgment is received, the message will be retransmitted up to 2 times, with a 15-second interval between attempts. During this time, the gateway will not be sending other configuration and control packets and they will be kept in a message queue. The publisher of the configure message shall thus set a timeout of 45 seconds before retry.

The acknowledgment payload state attribute can contain the following values:

  • ack if the message was successfully received by the node device,
  • fail if the message was not successfully received by the node device.

Example below shows the packet describing the feedback payload:

{
    "type": "acknowledgement",
    "payload":  {
  	  "state": "ack" 
    }
}

Failure to receive an acknowledgement payload or receiving a "fail" acknowledgement shall result in the controller reporting a communication error.

 no
/sauter/viasens/<network-id>/<node-address>/status

Node <node-address> from the <network-id> network sends its metadata to this topic. These messages are also RETAINED which allows other applications to fetch node's metadata at any point in time. Status messages are sent every minute after boot, until the configuration packet is received from the MQTT. This serves as a handshake mechanism. Additionally, upon entering and staying in the second quarter of the service menu, status messages will be sent every 10 seconds, regardless of the received configuration.

Example below shows the packet describing the metadata of a single node. The status packet may optionally include field calibration data if it is different from the default factory values. The MQTT API version is specified in the api attribute. This field is optional before FW 2.1 and is set to "2" from FW v2.1 onwards.

{
  "ffid": "FMS196F121",
  "serial": 815915802168,
  "boot-number": 1,
  "fw-version": "v2.3b25a942c3",
  "api": 2,
  "calibration": {
    "temperature": {
       "emissivity": 90
    },
   "occupancy": {
       "sensitivity": 2       
    },
   "illuminance": {
       "intercept": 0,
       "slope": 1
    }
  }
}

To this topic: Gateway publishes, MQTT broker subscribes.

yes

/sauter/viasens/<network-id>/presence

Last Will and Testament is a feature of MQTT for notifying the clients when the gateway ungracefully disconnects from the broker.

When the gateway connects to the broker, it will send 1 to the presence topic and when it disconnects, the broker will notify other clients by sending 0 to the same topic.

These messages are RETAINED which allows other applications to check if the gateway is connected to the broker at any point in time.

To this topic: Gateway publishes, MQTT broker subscribes.

yes

Gateway subscribes to the following topics:​

Topic Description
/sauter/viasens/<network-id>/+/control

Listens for Smart Sensor Data control packets.

Fetch the destination node address from topic (+ from the topic) and either forward data to the destination node or consume the data if it is addresses to the gateway itself.

/sauter/viasens/<network-id>/+/configure

Listens for Smart Sensor Config Data configuration packets.

Fetch the destination node address from topic (+ from the topic) and either forward data to the destination node or consume the data if it is addresses to the gateway itself.